home *** CD-ROM | disk | FTP | other *** search
/ PC Shareware 1997 February / PC Shareware 1997-02.iso / programy / e! / technote / ewtech.$08 / ewtech.008
Encoding:
Text File  |  1995-03-05  |  6.2 KB  |  135 lines
  1. E! for Windows - Technical Note #008
  2. *********************************************
  3. Using the EW API from an external application
  4. *********************************************
  5.  
  6. The EW API has been primarily designed to be used from an extension DLL
  7. loaded from EW itself.
  8.  
  9. However there's room for another kind of use. An external Windows program
  10. can interact with EW using the EW API. For example, we could (we certainly
  11. will) write a generic DDE Server programm accepting DDE messages and passing
  12. them to the EW API to communicate with EW itself.
  13.  
  14. If you decide to write such a program, you must be cautious and there's a
  15. few things you should be aware of.
  16.  
  17. When triggering certain functions, the EW API sends messages to the current
  18. Editor via the current Edit Window. The current Edit Window handle is
  19. continuously updated by EW and passed to the API DLL. This handle is stored
  20. in EWAPI.DLL's own data segment. When an Edit Window loses the focus, the
  21. handle is temporarily reset to 0 until another Edit Window gets the focus
  22. again. Meanwhile, there's no way to trigger an Edit Window related function
  23. because the call will be sent to the nowhere land. After all, an editing
  24. function has to apply to a given text. Please see below for a list a API
  25. functions that can be called at any time.
  26.  
  27. Your application can check whether an Edit Window has the focus by calling
  28. EWGetCurrentEditor or EWGetWindowHandle. Both functions return 0 if no Edit
  29. Window has the focus.
  30.  
  31. Since they can only be triggered when an Editor is active, this problem
  32. doesn't exist with Extension DLLs (except for hooks installed for certain
  33. events).
  34.  
  35. Another choice would have been to call the API editing functions for a given
  36. Editor explicitly. This would have made writing Extension DLLs a little bit
  37. more difficult because of the programming overhead needed to keep track of
  38. the currently valid Editors (maintaining a list of Editors and Edit Windows,
  39. setting up a notification hook to update the lists, etc...). Since using the
  40. EW API from an external application will not happen very often we have
  41. decided to make writing extension DLLs easier.
  42.  
  43. There are two methods for solving this problem.
  44.  
  45. Method #1
  46. *********
  47.  
  48. Before triggering one of the Edit Window related functions, your application
  49. must first set the focus to one of the Edit Window. You can keep track of
  50. the different Editors and Edit Windows by using the enumeration functions
  51. provided by the API. Once the focus has been set to an Edit Window, your
  52. application can call any API function safely while remaining in the
  53. background. Of course, once your application's current message has been
  54. processed, EW will immediately gain the input focus.
  55.  
  56. A good way to always know which Editor or Edit Window was the last one that
  57. had the focus is to install a notification hook (please see documentation)
  58. with the EWNotify_ActWinChanged event code. Such a hook can easily keep track
  59. of the currently active Edit Window.
  60.  
  61. Method #2
  62. *********
  63.  
  64. Before triggering an Edit Window related function, you can explicity set the
  65. current Editor and the Edit Window handle by using 2 undocumented functions
  66. that are normally used only by EW (both functions remain officially
  67. "undocumented" but have been added to EWAPIIMP.PAS and EWAPI.H):
  68.  
  69. **************************************************************************
  70. procedure EWSetEditorId(EditorId : longint);
  71. void FAR PASCAL EWSetEditor(long EditorId);
  72.  
  73. This function forces the current EditorId without giving it the focus.
  74. EditorId must be a valid Editor ID that you have retrieved earlier in your
  75. program by using the relevant API functions (EWEnumEditors or
  76. EWGetCurrentEditor).
  77.  
  78.  
  79. **************************************************************************
  80. procedure EWSetWindowHandle(H : HWnd);
  81. void FAR PASCAL EWSetWindowHandle(unsigned int H);
  82.  
  83. This function forces the handle of the current Edit Window without giving it
  84. the focus. H must be a valid Edit Window handle that you have retrieved
  85. earlier in your program by using the EWGetWindowHandle or EnumClones
  86. functions. Any call to an Edit Window related function will be forwarded to
  87. that window.
  88.  
  89.  
  90.  
  91. If you use these functions, please make sure that you keep both values in
  92. synch, that is, any window handle passed to EWSetWindowHandle must
  93. correspond to an Edit Window that belongs to the Editor which ID has been
  94. passed to EWSetEditorId. You can change the current Edit Window handle
  95. without changing the current Editor if the latter has clone windows but you
  96. can't change the current Editor Id whithout changing the Edit Window handle.
  97.  
  98. Any call to EWSetCurrentEditor will reset these values. Giving manually the
  99. focus to any Edit Window will also update these values (EW will call both
  100. functions).
  101.  
  102. This method is more elegant than the previous one but you should be very
  103. cautious when using it. Also, you should be aware that some functions may
  104. result in giving the focus to the target Edit Window (for example, when
  105. triggering functions that open a dialog box).
  106.  
  107.  
  108. Here is a list of EW API functions that are not related to an Edit Window.
  109. You can call them whenever you want, even if no Edit Window currently has
  110. the focus:
  111.  
  112.  
  113. EWEnumEditors               EWEnumClones                 EWSetHook
  114. EWRemoveHook                EWEditFile                   EWSetCurrentEditor
  115. EWGetCurrentEditor          EWFindRegular                EWAddMenuEntry
  116. EWRemoveMenuEntry           EWCallUserExt                EWGetGlobalFlag
  117. EWSetGlobalFlag             EWGetLocalFlag               EWSetLocalFlag
  118. EWGetSearchFlag             EWSetSearchFlag              EWSetFindPattern
  119. EWGetVersion                EWGetInstance                EWSaveAll
  120.  
  121.  
  122.  
  123. EWGetCurrentEditor will return 0 if no Edit Windows has the focus unless you
  124. have forced the current Editor Id using EWSetEditorId.
  125.  
  126. If you call EWCallUserExt, be sure that the called Extension DLL will not in
  127. turn trigger calls to Edit Window related functions while no Edit Window has
  128. the focus. This will do no harm but you will not get the expected result.
  129.  
  130. If you have any problem using the EW API, please let us know. We'll be
  131. pleased to help you and to add your suggestions to our todo list.
  132.  
  133. Patrick Philippot
  134. 07/02/93
  135.